<!DOCTYPE HTML>
<html lang="en">
<head>
<title>InStr() - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The InStr function searches for a given occurrence of a string, from the left or the right." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>InStr()</h1>

<p>Searches for a given occurrence of a string, from the left or the right.</p>

<pre class="Syntax">FoundPos := <span class="func">InStr</span>(Haystack, Needle <span class="optional">, CaseSensitive := false, StartingPos := 1, Occurrence := 1</span>)</pre>
<h2>Parameters</h2>
<dl>

  <dt>Haystack</dt>
  <dd><p>The string whose content is searched.</p></dd>
  
  <dt>Needle</dt>
  <dd><p>The string to search for.</p></dd>
  
  <dt>CaseSensitive</dt>
  <dd><p>If the parameter <em>CaseSensitive</em> is omitted or false, the search is not case sensitive (the method of insensitivity depends on <a href="StringCaseSense.htm">StringCaseSense</a>); otherwise, the case must match exactly.</p></dd>

  <dt>StartingPos</dt>
  <dd><p>If <em>StartingPos</em> is omitted, it defaults to 1 (the beginning of <em>Haystack</em>). Otherwise, specify 2 to start at the second character, 3 to start at the third, and so on.</p>
      <p>If <em>StartingPos</em> is beyond the length of <em>Haystack</em>, 0 is returned. <span class="ver">[AHK_L 57+]:</span> If <em>StartingPos</em> is 0 or negative, the search is conducted in reverse (right-to-left) beginning at that offset from the end.</p>
      <p>Regardless of the value of <em>StartingPos</em>, the return value is always relative to the first character of <em>Haystack</em>. For example, the position of "abc" in "123abc789" is always 4.</p></dd>

  <dt>Occurrence <span class="ver">[AHK_L 57+]</span></dt>
  <dd><p>If <em>Occurrence</em> is omitted, it defaults to the first match of the <em>Needle</em> in <em>Haystack</em>. Specify 2 for <em>Occurrence</em> to return the position of the second match, 3 for the third match, etc.</p></dd>

  </dl>
  
<h2>Return Value</h2>
<p>This function returns the position of an occurrence of the string <em>Needle</em> in the string <em>Haystack</em>. Position 1 is the first character; this is because 0 is synonymous with "false", making it an intuitive "not found" indicator.</p>
<p>An occurrence of an empty string (<code>""</code>) can be found at any position; therefore, if <em>Needle</em> is an empty string, the return value is 1. As a blank <em>Needle</em> would typically only be passed by mistake, it will be treated as an error in AutoHotkey v2.</p>

<h2>Remarks</h2>
<p>This function is a combination of <a href="IfInString.htm">IfInString</a> and <a href="StringGetPos.htm">StringGetPos</a>.</p>
<p><a href="RegExMatch.htm">RegExMatch()</a> can be used to search for a pattern (regular expression) within a string, making it much more flexible than InStr(). However, InStr() is generally faster than RegExMatch() when searching for a simple substring.</p>

<h2>Related</h2>
<p><a href="RegExMatch.htm">RegExMatch()</a>, <a href="StringGetPos.htm">StringGetPos</a>, <a href="IfInString.htm">IfInString</a>, <a href="StringCaseSense.htm">StringCaseSense</a>, <a href="IfIn.htm">if var in/contains MatchList</a>, <a href="IfBetween.htm">if var between</a>, <a href="IfIs.htm">if var is type</a></p>

<h2>Examples</h2>
<div class="ex" id="ExRetValue">
<p><a href="#ExRetValue">#1</a></p>
<pre>MsgBox % InStr("123abc789","abc") <em>; Returns 4</em></pre>
</div>

<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#2</a></p>
<pre>Haystack := "The Quick Brown Fox Jumps Over the Lazy Dog"
Needle := "Fox"
If InStr(Haystack, Needle)
    MsgBox, The string was found.
Else
    MsgBox, The string was not found.</pre>
</div>

<div class="ex" id="ExCaseSens">
<p><a href="#ExCaseSens">#3</a></p>
<pre>Haystack := "The Quick Brown Fox Jumps Over the Lazy Dog"
Needle := "the"
MsgBox % InStr(Haystack, Needle, false, 1, 2) <em>; case insensitive search, return start position of second occurence</em>
MsgBox % InStr(Haystack, Needle, true) <em>; case sensitive search, return start position of first occurence, same result as above</em>
</pre>
</div>

</body>
</html>
